home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Programming / AmigaE / Bin / Tools / efindhit.readme next >
Text File  |  1997-03-06  |  7KB  |  198 lines
  1. Short: EFindHit v1.2 (for Enforcer output)
  2. Type: dev/e
  3. Author: jason@fsel.com (Jason R. Hulance)
  4.  
  5. EFindHit can be used to find the line number of an Enforcer hit in an
  6. E program, given the offset information that Enforcer produces.
  7. Unlike normal FindHit programs, EFindHit reports the line numbers of
  8. hits in E modules, too (i.e., not just the main program).  And it can
  9. also tell you which function the code was in.
  10.  
  11.  
  12. Usage
  13. -----
  14.  
  15. To use EFindHit, the main source file *must* be compiled with the
  16. LINEDEBUG or DEBUG switches.  And if you want to track hits in modules
  17. used by the program, they too must be compiled with one of these
  18. switches.
  19.  
  20. If you want to see the names of functions as well, then you need to
  21. use the SYM switch, too, but only on the main source file.  This is
  22. especially useful for tracking hits in E internal functions.  If you
  23. don't use the SYM switch when compiling your source then EFindHit
  24. cannot reliably identify hits that occur in E internal functions (it
  25. may report them as coming from the last line of one of the sources,
  26. and flag those offsets that appear to be too far beyond the last
  27. line).
  28.  
  29. EFindHit takes the following arguments:
  30.  
  31.   EXECUTABLE/A,DEBUG/S,OFFSETS/M
  32.  
  33. So, you can supply a list of offsets.  Hexadecimal offsets can be
  34. specified using a leading '$' or '0x'.  Without these prefixes the
  35. offset is interpreted as decimal.
  36.  
  37. New to v1.2 is the DEBUG switch: see below for an illustrative
  38. example.
  39.  
  40.  
  41. Example
  42. -------
  43.  
  44. For example, consider the following output from Enforcer (when
  45. SegTracker is running):
  46.  
  47.   BYTE-READ from 00000000                        PC: 7833432C
  48.   USP:  7834B4B0 SR: 0004 SW: 0751  (U0)(-)(-)  TCB: 7828F188
  49.   Data: 00000000 0000000D 78348FB8 7829016C 00000001 1E0CCF39 78348FB8 00000001
  50.   Addr: 00000000 7828F1E4 783343AE 7829016C 7834B6C0 7834B4B4 78019864 --------
  51.   Stck: 00000000 7829016C 78334306 783341F2 00000000 00000000 00000000 00000000
  52.   Stck: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
  53.   ----> 7833432C - "xxx"  Hunk 0000 Offset 00000244
  54.   Name: "Shell Process"  CLI: "xxx"  Hunk 0000 Offset 00000244
  55.  
  56. The interested lines are the first and last.  The first line says the
  57. hit was a byte read from $00000000 (probably from dereferencing a NIL
  58. pointer). The last line says that the culprit was the program "xxx"
  59. and that the hit happened at offset $00000244.  (You might also
  60. consider using the STACKCHECK option of Enforcer to get the backtrace
  61. of the call stack.)
  62.  
  63. If "xxx" has been compiled with LINEDEBUG (or DEBUG) then you can run
  64. EFindHit on it to find the line number of the hit in one of the source
  65. files:
  66.  
  67.   1.System:> efindhit xxx $244
  68.   EFindHit works better if you compile with the SYM option
  69.   Offset $244: "xxx.e" line 5 [$242]
  70.  
  71. The first line of output is a reminder that using SYM makes EFindHit
  72. work better, then the information about the offset.  The trailing
  73. "[$242]" indicates the offset of the start of the code for line 5.
  74.  
  75. If you've compiled "xxx" with the SYM option too, then things get a
  76. bit better:
  77.  
  78.   1.System:> efindhit xxx $244
  79.   Offset $244: "xxx.e" line 5 [$242], in "fun()" [$238]
  80.  
  81. This also states the function the hit occurred in, and gives the
  82. offset of the start of code for that function ($238).
  83.  
  84. If you don't trust the output of EFindHit (???), then you can use the
  85. DEBUG switch to dump all the information from the executable that
  86. EFindHit uses.  (If this switch is specified then any supplied offsets
  87. are ignored.)  For example:
  88.  
  89.   1.System:> efindhit xxx debug
  90.   $00000000       *** Startup1 ***
  91.   $00000196       *** End of startup1 ***
  92.   $00000374       *** End of code ***
  93.   $00000236       fun()
  94.   $000001D2       zzz()
  95.   $00000196       external()
  96.   $00000284       main()
  97.   $000002DA       WriteF()
  98.   $0000036A       Char()
  99.   $0000023A    14 xxx.e
  100.   $00000240    15 xxx.e
  101.   $00000244    16 xxx.e
  102.   $00000288    22 xxx.e
  103.   $0000028E    23 xxx.e
  104.   $000001D6     4 zzz.e
  105.   $0000019A     8 xyz.e
  106.   $000001EE       *** Startup2 ***
  107.   $00000200       *** End of Startup2 ***
  108.  
  109. The first column is the offset, the second (if present) is the line
  110. number and the last column is the name of the file, the function or
  111. another significant part of the executable.  You could sort this
  112. output if you have pipes set up:
  113.  
  114.   1.System:> efindhit xxx debug | sort in: out:
  115.   $00000000       *** Startup1 ***
  116.   $00000196       *** End of startup1 ***
  117.   $00000196       external()
  118.   $0000019A     8 xyz.e
  119.   $000001D2       zzz()
  120.   $000001D6     4 zzz.e
  121.   $000001EE       *** Startup2 ***
  122.   $00000200       *** End of Startup2 ***
  123.   $00000236       fun()
  124.   $0000023A    14 xxx.e
  125.   $00000240    15 xxx.e
  126.   $00000244    16 xxx.e
  127.   $00000284       main()
  128.   $00000288    22 xxx.e
  129.   $0000028E    23 xxx.e
  130.   $000002DA       WriteF()
  131.   $0000036A       Char()
  132.   $00000374       *** End of code ***
  133.  
  134. Now it's really easy to see where any particular offset lies...
  135.  
  136.  
  137. Possible output
  138. ---------------
  139.  
  140. As well as complaining about errors (like you forgot to compile with
  141. LINEDEBUG), EFindHit might report:
  142.  
  143. 1) Offset $244: "xxx.e" line 5 [$242], in "fun()" [$238]
  144.  
  145. The offset is in the identified function in the main source.
  146.  
  147. 2) Offset $200: "xyz.e" line 11 [$1E8], near EXPORTed "external()" [$196]
  148.  
  149. The line number information for code in modules is more accurate than
  150. the function information, since only EXPORTed functions can be
  151. followed.  So EFindHit reminds you that the code at the offset is only
  152. "near" the EXPORTed function (i.e., some point after it but before the
  153. next EXPORTed function).
  154.  
  155. 3) Offset $280: E internal function "Char()"
  156.  
  157. The hit has occurred in an E internal function.  You probably want the
  158. backtrace in this case (the STACKCHECK option of Enforcer), so you can
  159. spot which function this was called from.
  160.  
  161. 4) Offset $190: E startup code
  162.  
  163. The hit has occurred outside user code, either when starting or
  164. cleaning up.  This didn't ought to happen unless your code has
  165. scribbled all over the place.  (These offsets will show up in the
  166. backtrace produced by the STACKCHECK option of Enforcer, as E code
  167. always starts in the startup code!)
  168.  
  169. 5) Invalid offset $330: not in code part
  170.  
  171. The hit didn't occur within the code of the executable being analysed.
  172. This might happen if you're running EFindHit on the wrong program or a
  173. different version from that which produced the hit.
  174.  
  175. 6) No line number for offset $200
  176.  
  177. EFindHit couldn't find a line number (but might still be able to
  178. identify a function, nonetheless, and this will be reported as "in" or
  179. "near" as appropriate [assuming you've compiled with the SYM option]).
  180.  
  181.  
  182. Limitations
  183. -----------
  184.  
  185. There's no symbol information (currently?) for any methods or for
  186. functions which are not EXPORTed from modules.  So it's not possible
  187. to put names to offsets in these bits of code (the line numbers should
  188. be sufficicient in these cases).  And offsets in methods/INCBIN/other
  189. data in the main source file will be reported as being "in" the
  190. nearest function before it.
  191.  
  192. The startup code recognition is pretty much specific to EC v3.2e.
  193. It's likely to change in future...
  194.  
  195.  
  196.  
  197. Have fun!
  198.